**********************************************
River City Ransom Password Algorithm
v0.0 2004.11.15
Author: Jerry McMahan Jr. (jerry@ensomnya.net)
**********************************************


*******
Copying
*******
This text is freely redistributable, as is.


*******************
About This Document
*******************
This text provides a description of the password algorithm for the NES
version of River City Ransom. The information provided should allow the
reader to generate passwords for a desired set of character data, or to
determine the character data associated with a particular password and
check it's validity. The information presented was reverse-engineered 
from the game, so there may be some errors. If you find any errors,
email me at jerry@ensomnya.net and let me know about them.


*************
Prerequisites
*************
To understand the material in this text, you'll need to have an
understanding of binary numbers and Boolean logic. Actually, you may be
able to do without it and pick it up along the way, but it'll make
things a lot easier. You will also need to know what binary coded
decimal is, to understand how the money values are stored. You can find
that in a lot of places online. Here's a good description:

http://en.wikipedia.org/wiki/Binary_coded_decimal


*****************
Table of Contents
*****************
1. Introduction
2. Password Description
   2.1 Data Stored in Each Position of the Password
   2.2 Password Algorithm
3. Numeric Values of Inventory Items 
4. Credits


***************
1. Introduction
***************
River City Ransom is notorious for its annoyingly long password system.
The player is required to enter 33 characters on a menu screen. Any
mistakes in copying just one of those characters will probably cause the
password to fail. Partly out of a desire to provide a correction for
this, and partly out of curiousity and boredom, I reverse-engineered the
password system. I've not done much checking on how correct this
information is, but all the checking I've done so far has shown has
verified this info. 

Interestingly, the information here can be used to generate passwords
that give your character stats, inventory items, or skills that aren't
possible to get through normal play. As a few examples of things I've
tried out that worked, I generated a password to give my character a
punch value of 0, to carry a "Smile" in his inventory, to equip a donut
(that is, have a '#' next to it, as in books that are read or shoes that
are worn), and to have the "Stone Hands" ability without having the
"Stone Hands" book in my inventory. There are probably a lot more things
you can do, but I just haven't tried.

As an interesting side note, if the information I've found about the
password system is thorough and completely correct, then there are 
562013623917344407265358750030539723015559577600000 valid passwords for
River City Ransom. The number of possible passwords you can enter, both
valid and invalid, is 124 to the 33rd power, or
1210362919824851463371550738227065461619969130596515513717925687066624.
That means that if you were to randomly enter values into the password
system, you'd have about a 1 in 2 quintillion (2 with 18 zeros after it)
to enter a working password. Actually, I may be wrong about the above,
but it sounds good anyway.

The information is presented in a kind of awkward manner, as it's mostly
reference information. It might be easier to look at the
"Examples" section first, and then use the other sections as reference.

Finally, for those interested, I've built written a password generator
and decrypter, both of which have a web interface. These tools, along
with the source code (in Python) are located at my website, here:

http://ensomnya.net/projects/rcr_password/index.html

(I apologize for the blatant plug of my website.) It's assumed that
there are bugs in these programs, but so far they've been tested to work
properly (I've even used them to make corrections in a couple of
incorrect passwords listed on GameFAQ).

If there's some point that I've not made clear enough in this text, or
if you have any comments, email me at jerry@ensomnya.net, and I'll see
if I can help you - and maybe, in the process, improve this document.


***********************
2. Password Description
***********************
The password system is actually a lot simpler than it might appear. For
a given set of character data, there are 32 passwords that represent
that data, corresponding with a key included with the password. This
accounts for seeing different passwords upon entering and exiting the
password screen several times in a row. If you do it enough times,
you'll eventually begin to see the same passwords reappear. 

The aforementioned key is the last letter in the password. It can take
on one of 32 values, 'A' through 'Z' or 'a' through 'f'. The key is used
in the algorithm to encrypt or decrypt the character data, as will be
explained below.


************************************************
2.1 Data Stored in Each Position of the Password
************************************************

Each letter in the password represents a certain value in the game which
will now be explained. The password is always of the following format,
where each of the following numbers represents a position in the
password:

01 02 03 04 05 06 07 08 09 10 11
12 13 14 15 16 17 18 19 20 21 22
23 24 25 26 27 28 29 30 31 32 33

For example, in the password,

 C  K  X  I  E  e  S  f  q  s  X
 J  P  5  f  M  U  F  D  W  G  M
 S  H  K  L  b  S  O  N  M  O  A

01 = C, 02 = K, 03 = X, 04 = I, and so on.

Except for position 33, the raw value represented by each character in 
each of these positions can range from 0 to 63. For position 33, it 
ranges from 0 to 31. The values represented by each of these characters 
in these positions follows. An overview is presented, followed by a more
in-depth description of each of the values.


Summary:

01 - Punch
02 - Kick
03 - Weapon
04 - Throwing
05 - Agility
06 - Defense
07 - Strength
08 - Will Power
09 - Lower bits of Stamina
10 - Lower bits of Max Power
11 - High bits of Stamina and Max Power
12 - Active skills
13 - Lower bits of cents in money
14 - Lower bits of ones and tens digits in money
15 - Lower bits of hundreds digit in money
16 - High bits of cents, ones & tens digits, and hundreds digits
17 - Lower bits of inventory slot 1
18 - Lower bits of inventory slot 2
19 - High bits of inventory slot 1 and 2
20 - Lower bits of inventory slot 3
21 - Lower bits of inventory slot 4
22 - High bits of inventory slot 3 and 4
23 - Lower bits of inventory slot 5
24 - Lower bits of inventory slot 6
25 - High bits of inventory slot 5 and 6
26 - Lower bits of inventory slot 7
27 - Lower bits of inventory slot 8
28 - High bits of inventory slot 7 and 8
29 - Bosses defeated 1
30 - Bosses defeated 2
31 - Bosses defeated 3
32 - "Checksum" of values in positions 01 through 31
33 - Password key


In-depth:

01: 
The total value of Punch.

02:
The total value of Kick.

03: 
The total value of Weapon.

04: 
The total value of Throwing.

05: 
The total value of Agility.

06: 
The total value of Defense.

07: 
The total value of Strength.

08: 
The total value of Will Power.

09:
The first 6 bits of Stamina. 

10: 
The first 6 bits of Max Power.

11:
If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

The highest bit of Stamina is in bit 2 and the highest bit of Max
Power is in the bit 0. To reconstruct Stamina, you integer divide this
value by four (that is, truncate the value), multiply the result by
sixty-four, and add what you get to the value in position 09. To
reconstruct Max Power, you take this value modulo 2 (or, equivalently,
mask out the high 7 bits), multiply the result by 64, and add it to the
value in position 10. 

12:
This value explains what fighting skills your character has. Each bit
represents a value. If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, the bit values correspond to the different
skills as follows

bit 0 - Stone Hands
bit 1 - Dragon Feet
bit 2 - Grand Slam
bit 3 - Acro Circus
bit 4 - Javelin Man
bit 5 - Fatal Steps

A bit set to 1 means the skill is active. Otherwise, the skill is
inactive.

13:
The lowest 6 bits of the cents value (that is, the number of cents in
your money statistic). For example, with $123.45, the cents value is 
"45".

14:
The lowest 6 bits of the first two digits of the whole number portion of
your money statistic. For example, with $123.45, the first two digits
of the whole number portion of the money is "23".

15:
The lowest 6 bits of the hundreds digit of your money statistic. For
example, with $123.45, the hundreds digit is "1".

16:
If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

Bits 5 and 4 correspond to the highest bits (bits 7 and 6, respectively)
of the cents value (from position 13). 

Bits 3 and 2 correspond to the highest bits (bits 7 and 6, respectively)
of the value in position 14.

Bits 1 and 0 correspond to the highest bits (bits 7 and 6, respectively)
of the value in position 15. Supposedly, these bits will always be zero,
because you're not supposed to be able to get more money than $999.99,
but there is code in the game to store the high bits here in this value.
Whether this has an effect on anything or not is unknown.

The money is stored in binary-coded decimal, in three different
variables, one for each of the values mentioned in the description of
position 13, 14, and 15. So for a money statistic of "$99.00", the cents
value would be 0, the ones and tens value would be 153 (because 153 is
0x99 in hexadecimal), and the hundreds value would be 0. 

17:
This is the first 6 bits of the value for the first inventory slot. The
inventory items corresponding to the different values in these locations
is listed in Section 5 of this document.

18:
This is the first 6 bits of the value for the second inventory slot.

19:
If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

Bits 3 and 2 correspond to bits 7 and 6 of the value for the first
inventory slot. Bits 1 and 0 correspond to bits 7 and 6 of the value for
the second inventory slot.

20:
This is the first 6 bits of the value for the third inventory slot. 

21:
This is the first 6 bits of the value for the fourth inventory slot.

22:
If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

Bits 3 and 2 correspond to bits 7 and 6 of the value for the third
inventory slot. Bits 1 and 0 correspond to bits 7 and 6 of the value for
the fourth inventory slot.

23:
This is the first 6 bits of the value for the fifth inventory slot. 

24:
This is the first 6 bits of the value for the sixth inventory slot.

25:
If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

Bits 3 and 2 correspond to bits 7 and 6 of the value for the fifth
inventory slot. Bits 1 and 0 correspond to bits 7 and 6 of the value for
the sixth inventory slot.

26:
This is the first 6 bits of the value for the seventh inventory slot. 

27:
This is the first 6 bits of the value for the eighth inventory slot.

28:
If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

Bits 3 and 2 correspond to bits 7 and 6 of the value for the seventh
inventory slot. Bits 1 and 0 correspond to bits 7 and 6 of the value for
the eighth inventory slot.

29:
The bits in the value stored in this position correspond to bosses
you've defeated, or events you've gone through (like talking to Roxy or
rescuing Cyndi). 

If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

bit 0 - Clyde
bit 1 - Benny
bit 2 - Thor
bit 3 - Otis
bit 4 - Ivan

30:
The bits in the value stored in this position correspond to bosses
you've defeated, or events you've gone through (like talking to Roxy or
rescuing Cyndi). 

If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing
the most significant bit, then the following description applies.

bit 0 - Roxy
bit 2 - Cyndi
bit 3 - Moose
bit 4 - Mojo
bit 5 - Turk

31:
The bits in the value stored in this position correspond to bosses
you've defeated, or events you've gone through (like talking to Roxy or
rescuing Cyndi). 

If you order the bits like so:

|7|6|5|4|3|2|1|0|

with bit 0 representing the least significant bit and bit 7 representing

the most significant bit, then the following description applies.

bit 0 - Rocko
bit 1 - Blade
bit 2 - Randy*
bit 3 - Andy*

*Note - I'm not sure if these are reversed or not. The twins look
identical, so I'm not sure which one is which. But it really doesn't
matter.

32:
The "checksum" of the values in position 01 through 31. To calculate it,
simply add all the values in positions 01 through 31 and keep only the
lower 6 bits. If the value input here with the password doesn't match
what the game calculates for the password, a "Wrong Password" error will
occur.

33:
This is the password key. It's a value ranging from 0 to 31 that is
picked at random and used in the encoding / decoding of the password.
It's used to create 32 different passwords for each set of character
data.


**********************
2.2 Password Algorithm
**********************
The password algorithm is pretty easy to follow. To encrypt a value, set
up each position of the password with an appropriate value. Then for the
first 32 positions, the following formula is applied:

x_coded[x] = (key + kconstant[x]) XOR value[x]

where x_coded[x] is the intermediate result, key is the value in 
position 33, kconstnat[x] is a special number that's different for each
position and is always added as in the formula (probably to make the
password appear more random and irregular), and value[x] is the value
stored in the position. The "XOR" operation in the equation is a bitwise
XOR operation - that is, it performs an XOR on each bit (like the "^"
operator in C, and similar operators).

The kconstant is as follows, with the position it refers to preceding
the constant:

Position	Constant
--------------------
01:			13
02:			5	
03:			24
04:			7
05:			11
06:			17
07:			29
08:			16
09:			21
10:			19
11:			23
12:			9
13:			15
14:			25
15:			31
16:			12
17:			20
18:			5
19:			3
20:			22
21:			6
22:			12
23:			18
24:			7
25:			10
26:			11
27:			27
28:			18
29:			14
30:			13
31:			12
32:			24


Notice that the final position, 33, doesn't have this constant added to
it, or anything XOR'ed with it. 

Once these intermediate values are calculated, the number 192 is added
to them. Then the resulting number is used as an index into the
following table to generate the final password.


Character Chart
---------------
255 = B'
254 = A'
253 = 9
252 = 8
251 = 7
250 = 6
249 = 5
248 = 4
247 = 3
246 = 2
245 = 1
244 = 0
243 = z
242 = y
241 = x
240 = w
239 = v
238 = u
237 = t
236 = s
235 = r
234 = q
233 = p
232 = o
231 = n
230 = m
229 = l
228 = k
227 = j
226 = i
225 = h
224 = g
223 = f
222 = e
221 = d
220 = c
219 = b
218 = a
217 = Z
216 = Y
215 = X
214 = W
213 = V
212 = U
211 = T
210 = S
209 = R
208 = Q
207 = P
206 = O
205 = N
204 = M
203 = L
202 = K
201 = J
200 = I
199 = H
198 = G
197 = F
196 = E
195 = D
194 = C
193 = B
192 = A


It's worth noting from this chart that the only characters with accent
mark following them (denoted by the single quote, ', following the
letter) are A and B. As far as I can tell, there are never any passwords
given by the game with the accent mark on any other character, although
depending on what value they represent, it may be possible to generate
passwords with them. That would require more research (and some kind of
motivation) to find out.

And that's it. To decrypt the passwords, just reverse the above steps.

I was going to provide some examples, as I know it's a bit difficult to
follow the real meaning of all this means with what I've written here,
but I'll save that for a future improvement, if anyone requests it. For a
working example, you can, as I mentioned above, look at the source code
of the password generator and decrypter programs I've written that are
available from my website at this URL:

http://ensomnya.net/projects/rcr_password/index.html

I don't really know anything about cryptography and what not, but I read
an article online describing "One-Time Pad" ciphers, and that seems to 
be what this is. If anyone could confirm or correct that, I'd appreciate
it.

Have fun messing with these passwords. If you find anything that doesn't
match up with the information in this document, email me and let me
know.


*************************************
3. Numeric Values of Inventory Items 
*************************************
The following list has the value, followed by the item. I've found that
sometimes the password will cause items with different descriptions to
be placed in the inventory, but they seem to represent the same things
as in this list. Also, items that you can't typically hold in your
inventory seem to cause garbled messages to appear when you try to use
them.

The possible values actually go up to 255. However, once the value
exceeds 127, the inventory item becomes the same as the item
corresponding to the value that is 128 numbers below that number, only
it has the "#" sign at the beginning (like when books are read). For
example, if the value is 130, then the item will be 130 - 127 = 3, which
is bagel, only it will have a "#" in front of it, making it "#bagel".

0 nothing
1 donut
2 muffin
3 bagel
4 honey_bun
5 croissant
6 sugar
7 toll_house
8 maple_pecan
9 oatmeal
10 brownie
11 mint_gum
12 lolly_pop
13 jaw_breaker
14 rock_candy
15 fudge_bar
16 salad_paris
17 onion_soup
18 cornish_hen
19 veal_walle
20 vita-mints
21 digestol
22 recharge!
23 karma_jolt
24 omni_elixir
25 date_saver
26 love_potion
27 antedote_12
28 r_&_b
29 rock
30 pop
31 soul
32 classical
33 sneakers
34 boat_shoes
35 loafers
36 army_boots
37 texas_boots
38 slippers
39 thongs
40 sandals
41 mod_boots
42 insoles
43 maze_craze
44 decathlete
45 hyper_ball
46 techno_belt
47 teddy_bear
48 stone_hands
49 dragon_feet
50 grand_slam
51 acro_circus
52 javelin_man
53 fatal_steps
54 scandal_rag
55 comic_times
56 mystic_seer
57 nuclear_spy
58 indian_lore
59 excaliber
60 zeus_wand
61 rodan_wing
62 gold_medal
63 isis_scroll
64 sirloin
65 rib-eye
66 t-bone
67 lamb_leg
68 merv_burger
69 cheese_merv
70 fish_merv
71 mondo_merv
72 milk
73 iced_tea
74 soda
75 merv_malt
76 merv_fries
77 merv_rings
78 apple_pies
79 spicy_chili
80 smile
81 chickwich
82 dark_meat
83 white_meat
84 combination
85 lemonade
86 gravy
87 biscuits
88 corn_cobber
89 cole_slaw
90 coffee
91 tea
92 hot_cocoa
93 pancakes
94 waffles
95 ice_cream
96 roman_shake
97 cola_float
98 nero_pizza
99 lasagna
100 fresh_juice
101 lemon_tea
102 herbal_tea
103 carrot_cake
104 pound_cake
105 egg
106 octopus
107 squid
108 conger_eel
109 prawn
110 salmon
111 ark_shell
112 sea_urchin
113 halibut
114 swordfish
115 salad_roll
116 tuna_roll
117 shrimp_roll
118 mixed_roll
119 egg_roll
120 fried_rice
121 garlic_pork
122 pepper_beef
123 chow_mein
124 sauna
125 no_thanks
126 nothing
127 main_menu


**********
4. Credits
**********
Thanks to:

- Technos for making such a cool game.
- The makers of FCEU, as their debugger made this much easier to figure
  out, as did their emulator.
- Zdravko Beikov, his "Ultimate Cheating Guide" listed some of the stat 
  locations in memory, saving me the trouble of having to find them
  myself.